<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head><meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"/>
<title>Nutz Java 编码规范 (V1.0)</title><link href="../zdoc.css" rel="stylesheet" type="text/css"/><link href="../_rs/site.css" rel="stylesheet" type="text/css"/><script src="../_rs/site.js" language="Javascript"></script><script src="../_rs/jquery.js" language="Javascript"></script><script src="../_rs/z.js" language="Javascript"></script>
</head>
<body><a name="top"></a>
<div class="zdoc_header">Nutz Java 编码规范 (V1.0)</div>
<div class="zdoc_author"><em>By:</em><b>zozoh</b><a href="mailto:zozohtnt@gmail.com">&lt;zozohtnt@gmail.com&gt;</a></div>
<div class="zdoc_body">
<ul class="zdoc_index_table">
<li>
<div><span class="num">1</span><a href="#0_规范的规范">0. 规范的规范</a></div>
</li>
<li>
<div><span class="num">2</span><a href="#1_代码格式">1. 代码格式</a></div>
</li>
<li>
<div class="zdoc_folder"><span class="num">3</span><a href="#2_命名">2. 命名</a></div>
<ul>
<li>
<div><span class="num">3.1</span><a href="#21_包">2.1 包</a></div>
</li>
<li>
<div><span class="num">3.2</span><a href="#22_类和接口">2.2 类和接口</a></div>
</li>
<li>
<div><span class="num">3.3</span><a href="#23_成员变量">2.3 成员变量</a></div>
</li>
<li>
<div><span class="num">3.4</span><a href="#24_常量">2.4 常量</a></div>
</li>
<li>
<div><span class="num">3.5</span><a href="#25_局部变量">2.5 局部变量</a></div>
</li>
<li>
<div><span class="num">3.6</span><a href="#26_成员函数和静态函数">2.6 成员函数和静态函数</a></div>
</li>
</ul>
</li>
<li>
<div class="zdoc_folder"><span class="num">4</span><a href="#3_注释">3. 注释</a></div>
<ul>
<li>
<div><span class="num">4.1</span><a href="#31_类_Java_Doc">3.1  类 Java Doc</a></div>
</li>
<li>
<div><span class="num">4.2</span><a href="#32_函数_Java_Doc">3.2  函数 Java Doc</a></div>
</li>
<li>
<div><span class="num">4.3</span><a href="#33_字段_Java_Doc">3.3  字段 Java Doc</a></div>
</li>
<li>
<div><span class="num">4.4</span><a href="#34_函数内部注释">3.4  函数内部注释</a></div>
</li>
</ul>
</li>
<li>
<div><span class="num">5</span><a href="#4_编程">4. 编程</a></div>
</li>
<li>
<div><span class="num">6</span><a href="#5_单元测试">5. 单元测试</a></div>
</li>
</ul>
<div class="hr"><b></b></div>
<h1><a name="0_规范的规范"></a>0. 规范的规范</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<p></p>
<ol type="1">
<li>本规范的每一条目必须无二义性，并且可执行。否则作废</li>
<li>本规范的条目分为两个级别:
<ul type="disc">
<li>规则 - <span style="color:#FF0000;"><b>R</b></span></li>
<li>建议 - <span style="color:#008800;"><b>S</b></span></li>
</ul>
</li>
<li>本规范所有的“规则”条目必须被遵守</li>
</ol>
<div class="hr"><b></b></div>
<h1><a name="1_代码格式"></a>1. 代码格式</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-使用统一的 Eclipse 的代码格式: <a href="http://code.google.com/p/nutz/source/browse/trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml">http://code.google.com/p/nutz/source/browse/trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml</a>
<ul type="disc">
<li>请从 svn 的 trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml 获得此文件</li>
</ul>
</li>
<li><span style="color:#008800;"><b>S</b></span>-非 Eclipse 用户请阅读上述 XML 代码自行遵守
<ul type="disc">
<li><i>基本上我们没有为非 Eclipse 用户指定规范，我们还没有一个好办法</i></li>
</ul>
</li>
</ol>
<div class="hr"><b></b></div>
<h1><a name="2_命名"></a>2. 命名</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<div class="hr"><b></b></div>
<h2><a name="21_包"></a>2.1 包</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-包名必须全部小写，2个以内单词。
<ol type="a">
<li><span style="color:#008800;"><b>S</b></span>-最好为 1 个单数名词</li>
</ol>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-所有项目的包要以 “org.nutz” 为父 包 。</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="22_类和接口"></a>2.2 类和接口</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#008800;"><b>S</b></span>-最好为名词</li>
<li><span style="color:#FF0000;"><b>R</b></span>-命名类和接口时，需要将所有单词的首字母大写。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-接口的命名不采用首字母为 I 或加上 IF 后缀的命名方式 。例 如 ：IBookDao 、 BookDaoIF 等 。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-抽象类必须使用 Abstract 作为类名的前缀，而接口建议使用 Interface 作为 接口名后缀。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-异常类应该使用 Exception 做为 名称 后缀。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-如果是运行一次就抛弃的类，以 ing 结尾，比如Rendering</li>
<li><span style="color:#FF0000;"><b>R</b></span>-类名尽量短，但是最好不要缩写，如果缩写，必须为特别常用的类，比如 org.nutz.dao.Cnd
<ul type="disc">
<li>因为调用者书写你的类名太长，他(她)的IDE会自动替他(她)换行，他会觉得有点不爽</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-不要和 Java 的标准库中的类名冲突，比如 Class, Object, String 等
<ul type="disc">
<li>如果冲突，就表示你极其藐视 Java 标准库中的那个的设计</li>
<li>调用者需要花更多的时间和代码来明确他使用的是你的类, 而不是标准库中的那个</li>
</ul>
</li>
<li><span style="color:#008800;"><b>S</b></span>-以下情况可以允许写奇怪类名 -- <sup>名称简短，让人一眼不知道什么意思，用了以后一眼就能知道什么意思</sup>
<ul type="disc">
<li>类特别常用</li>
<li>类非常特殊，难以归类</li>
<li>私有类或内部类</li>
<li>不推荐其他人调用的 公有、保护、默认类
<ul type="circle">
<li>起个奇怪的名字，就是不想让你关心这个类的代码</li>
</ul>
</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-缺省接口实现应该使用 Default 名称 前缀 。例 如 ： DefaultEntityMaker。
<ul type="disc">
<li>也可以采用 Impl 作为后缀，表示这个实现为此接口的最优实现或者唯一实现</li>
</ul>
</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="23_成员变量"></a>2.3 成员变量</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#008800;"><b>S</b></span>-最好为单数名词</li>
<li><span style="color:#FF0000;"><b>R</b></span>-能 private 就不要 default，能 default 就不要 protected，最好不要 public</li>
<li><span style="color:#FF0000;"><b>R</b></span>-如果是集合或数组，用复数名词
<ul type="disc">
<li>Map pets， 比 Map petMap 要好</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-不要用一个字母，尤其是 i，你可以用 index 或者 cursor 来代替</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="24_常量"></a>2.4 常量</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-命名常量（带有 final 修饰符的域）时需分隔。如 ： public final int MAX_VALUE = 30 。</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="25_局部变量"></a>2.5 局部变量</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-局域变量名要尽量短，推荐用缩写，比如 StringBuilder sb</li>
<li><span style="color:#FF0000;"><b>R</b></span>-总的来说局部变量请随意命名，越短越好</li>
</ol>
<p>比如这个就不好</p>
<pre> public String abc(String str){
	AbcObjectSet abcObjectSet = new AbcObjectSet();
	abcObjectSet.setName(str);
	return abcObjectSet.getBrief();
 }
</pre>
<p>而这个就很容易阅读了：</p>
<pre> public String abc(String str){
	AbcObjectSet aos = new AbcObjectSet();
	aos.setName(str);
	return aos.getBrief();
 }
</pre>
<p></p>
<div class="hr"><b></b></div>
<h2><a name="26_成员函数和静态函数"></a>2.6 成员函数和静态函数</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-除了 setter / getter，其他的函数采用动词或者动名短语</li>
<li><span style="color:#008800;"><b>S</b></span>-以下情况可以允许写奇怪函数 -- <sup>名称简短，让人一眼不知道什么意思，用了以后一眼就能知道什么意思</sup>
<ol type="a">
<li>函数特别常用</li>
<li>函数非常特殊</li>
<li>私有函数或默认函数</li>
</ol>
</li>
<li><span style="color:#008800;"><b>S</b></span>-支持链式赋值的 setter 允许写成 ，并且也可以支持同名 getter
<pre>// Setter
public Pet name(String name){
	this.name = name;
	return this;
}

// Getter
public String name(){
	return this.name;
}
</pre>
</li>
</ol>
<div class="hr"><b></b></div>
<h1><a name="3_注释"></a>3. 注释</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-注释必须和代码保持同步 。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-注释中的第一个句子要以（英文）句号、问号或者感叹号结束。 Java成工具会将注释中的第一个句子放在方法汇总表和索引中。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-如果注释中有超过一个段落，用 &lt;P&gt; 标签 分隔。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-如果注释中有多个章节，用 &lt;H2&gt; 标签声明每个章节的标题。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-如果注释需要换行，用 &lt;BR&gt; 标签。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-示例代码以 &lt;PRE&gt;&lt;/PRE&gt; 包裹。</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="31_类_Java_Doc"></a>3.1  类 Java Doc </h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-要著名作者，格式为 @Author XiaoMing(xm@gmail.com)</li>
<li><span style="color:#FF0000;"><b>R</b></span>-继承的方法可以省略注释，但是被继承方法必须有注释。</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="32_函数_Java_Doc"></a>3.2  函数 Java Doc </h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-简单的 get/set 方法可以省略注释。</li>
<li><span style="color:#FF0000;"><b>R</b></span>-继承的方法可以省略注释，但是被继承方法必须有注释。</li>
</ol>
<div class="hr"><b></b></div>
<h2><a name="33_字段_Java_Doc"></a>3.3  字段 Java Doc </h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ul type="disc">
<li><span style="color:#FF0000;"><b>R</b></span>-没有更多说明了</li>
</ul>
<div class="hr"><b></b></div>
<h2><a name="34_函数内部注释"></a>3.4  函数内部注释</h2>
<div style="float:right;"><a href="#top">Top</a></div>
<ul type="disc">
<li><span style="color:#FF0000;"><b>R</b></span>-行注释和块注释都是可以被接受的</li>
<li><span style="color:#FF0000;"><b>R</b></span>-不要写 JAVA DOC，没意义</li>
<li><span style="color:#FF0000;"><b>R</b></span>-代码质量不好但能正常运行，或者还没有实现的代码用 “ //TODO: ”</li>
<li><span style="color:#FF0000;"><b>R</b></span>-在 if ... else .. 分支上做注释格式应该如下：
<pre>// comments for case A
if(xxxx){
	//TODO you code here
}
/*
 * Multipline comments for case B
 */
else if(xxxxx){
	//TODO you code here
}
// comments for default case
else{
	//TODO you code here
}
</pre>
</li>
</ul>
<div class="hr"><b></b></div>
<h1><a name="4_编程"></a>4. 编程</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-你的每一次提交，必须都是编译通过的</li>
<li><span style="color:#FF0000;"><b>R</b></span>-你的每一次提交，最好都是通过 JUnit 测试的
<ul type="disc">
<li>除非有特别的情况 -- 比如你要和其他人分享的修改</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-无论任何时候，同样的功能，一段更短的代码，总比更长的代码要好
<ul type="disc">
<li>这里的“短”，主要指的是“逻辑”短，而不是“字符长度”短</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-删掉一段代码的贡献，比增加一段代码的贡献要大，至少不比它小</li>
<li><span style="color:#FF0000;"><b>R</b></span>-避免过度设计
<ul type="disc">
<li>先让代码能工作，然后重构成为优美的代码</li>
<li>你需要知道，“接口”固定了架构，“类” 不是，当它进化为接口的时候就固定了</li>
<li>代码结构设计请遵循《<a href="http://blog.sina.com.cn/s/blog_4b19fa3701000720.html">草坪原则</a>》</li>
</ul>
</li>
</ol>
<div class="hr"><b></b></div>
<h1><a name="5_单元测试"></a>5. 单元测试</h1>
<div style="float:right;"><a href="#top">Top</a></div>
<ol type="1">
<li><span style="color:#FF0000;"><b>R</b></span>-用例名请用 "<span style="color:#0000FF;"><b>长名</b></span>" - 一句话，用下划线_代替空白
<ul type="disc">
<li>通过这个名字，基本可以了解测试是干什么的</li>
</ul>
</li>
<li><span style="color:#FF0000;"><b>R</b></span>-主要接口和实现类要尽可能多的被用例覆盖</li>
</ol>
</div>
<div class="zdoc_footer"><em>By:</em><b>zozoh</b><a href="mailto:zozohtnt@gmail.com">&lt;zozohtnt@gmail.com&gt;</a></div>
</body>
</html>